home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / Sprites < prev    next >
Encoding:
Text File  |  1988-12-06  |  4.1 KB  |  113 lines
  1. > Wimp.Sprites
  2.  
  3. New calls
  4. ---------
  5.  
  6.         Wimp_SpriteOp
  7.         Wimp_BaseOfSprites
  8.  
  9.         *IconSprites <filename>
  10.         window areaCBptr = 1 ==> use common sprite area
  11.           icon areaCBptr = 1 ==> use common sprite area
  12.  
  13.  
  14. Overview
  15. --------
  16.  
  17. To allow for sharing of sprite data between wimp tasks, the Wimp supports a
  18. set of shareable sprites, which is used by the Wimp utilities, and can also
  19. be used by applications.  The area is split in two: one area is held in ROM,
  20. and the other is held in the RMA - the Wimp will use the RMA sprites in
  21. preference, but will revert to the ROM area if the relevant sprite is not
  22. found.  A special call has been provided to access these sprites, and there
  23. is a *command to add more sprites into the area, which copes with extending
  24. the RMA block suitably.
  25.  
  26. (See also Wimp.Colours to see how sprites are coped with in the different
  27. screen modes, and Wimp.Icons for the Sprite+Text icon facility).
  28.  
  29.  
  30. Loading sprites
  31. ---------------
  32.  
  33.         Wimp_SpriteOp
  34.         Entry:  R0 = 11 (SpriteReason_MergeSpriteFile)
  35.                 R2 --> name of sprite file
  36.         Exit:   sprites merged into the common sprite area
  37.                 the sprite area may have moved as a result
  38.  
  39.         *IconSprites <filename>
  40.  
  41. The *iconsprites call simply calls Wimp_SpriteOp, and is provided as a simple
  42. means of loading sprites from a boot file.
  43.  
  44.  
  45. Accessing Sprites
  46. -----------------
  47.  
  48.         Wimp_SpriteOp
  49.         Entry:  R0 = reason code (as for OS_SpriteOp)
  50.                 R1 doesn't matter
  51.                 R2.. parameters for OS_SpriteOp
  52.         Exit:   R2.. = results from OS_SpriteOp
  53.         Error:  "Bad parameter passed to Wimp in R0" if invalid reason code
  54.  
  55. The reason codes passed to Wimp_SpriteOp are exactly analagous to those
  56. passed to OS_SpriteOp, except that the Wimp will not allow any operations
  57. other than MergeSpriteFile which modify the contents of the sprite area.  For
  58. all read operations, the Wimp will attempt to perform the operation on the
  59. RMA sprite area, and if the error "Sprite does not exist" is returned, will
  60. try the operation on the ROM sprite area.
  61.  
  62. Note that only bits 0..7 of R0 are used: &100 is always added to this value,
  63. so R2 always points to the sprite name, rather than the sprite itself.
  64.  
  65. In addition, another SWI is provided which allows the inquisitive application
  66. to find out where the sprite areas are located.  Since the address of the RMA
  67. sprite area can change whenever more sprites are merged into it, however, the
  68. address should be re-read whenever it is needed.  Wimp_SpriteOp should always
  69. be used in preference to this SWI, if possible.
  70.  
  71.         Wimp_BaseOfSprites
  72.         Exit:  R0 --> base of ROM sprite area
  73.                R1 --> base of RMA sprite area
  74.                note that the RMA sprite area can move about subsequently
  75.  
  76.  
  77. Using the common sprites in icons
  78. ---------------------------------
  79.  
  80. A more usual way of accessing the common sprite area is to program the
  81. 'areaCBptr' field in a window, or the areaCBptr field in an indirected sprite
  82. icon:
  83.  
  84.         Wimp_CreateWindow
  85.         Entry:  R1 --> window definition
  86.                 R1!64 = 0 ==> use system area for sprite icons
  87.                       = 1 ==> use common sprite area
  88.                       > 1 ==> use specified sprite area
  89.  
  90.         Icon block:
  91.                 + 0..15 = bounding box
  92.                 + 16    = flags
  93.                           bit 1 set ==> icon contains a sprite
  94.                           bit 8 set ==> icon data is indirected
  95.                 + 20    = pointer to sprite name / sprite definition
  96.                 + 24    = sprite area pointer (see above)
  97.                 + 28    = length of name block
  98.                         = 0 ==> block!20 is a sprite pointer
  99.                         > 0 ==> block!20 is a sprite name pointer
  100.  
  101. The latter facility allows for icons within a window to have different sprite
  102. areas associated with them, which is particularly useful when dealing with
  103. sprites in the icon bar (which is shared between many tasks).
  104.  
  105.  
  106. Wimp's use of sprites
  107. ---------------------
  108.  
  109. See the chapter 'Wimp.Colours' for a description of how the Wimp handles
  110. sprites in modes with other than 16 colours.
  111.  
  112.  
  113.